home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 22 / Amiga Format AFCD22 (Jan 1998, Issue 106).iso / -seriously_amiga- / shareware / programming / other / saferpatches / saferpatches.readme < prev    next >
Text File  |  1997-11-17  |  10KB  |  283 lines
  1. Short:    Safer Setfunctions Debug Tools
  2. Uploader: thor@math.tu-berlin.de (Thomas Richter)
  3. Author:   thor@math.tu-berlin.de (Thomas Richter)
  4. Type:     dev/debug
  5. Version:  2.07
  6.  
  7. _____________________________________________________________________________
  8.  
  9.                         The THOR-Software Licence
  10.  
  11.  
  12. This License applies to the computer programs known as "SaferPatches" and 
  13. "ShowPatch". The "Program", below, refers to such program.
  14.  
  15.  
  16. The programs and files in this distribution are freely distributable
  17. under the restrictions stated below, but are also Copyright (c)
  18. Thomas Richter.
  19.  
  20.  
  21. Distribution of the Program by a commercial organization without written
  22. permission from the author to any third party is prohibited if any payment
  23. is made in connection with such distribution, whether directly
  24. (as in payment for a copy of the Program) or indirectly (as in payment
  25. for some service related to the Program, or payment for some product
  26. or service that includes a copy of the Program "without charge";
  27. these are only examples, and not an exhaustive enumeration of prohibited
  28. activities). However, the following methods of distribution involving
  29. payment shall not in and of themselves be a violation of this restriction:
  30.  
  31.  
  32. (i) Posting the Program on a public access information storage and
  33. retrieval service for which a fee is received for retrieving information
  34. (such as an on-line service), provided that the fee is not
  35. content-dependent (i.e., the fee would be the same for retrieving the same
  36. volume of information consisting of random data).
  37.  
  38.  
  39.  
  40. (ii) Distributing the Program on a CD-ROM, provided that the files
  41. containing the Program are reproduced entirely and verbatim on such
  42. CD-ROM, and provided further that all information on such CD-ROM be
  43. redistributable for non-commercial purposes without charge.
  44.  
  45.  
  46.  
  47. Everything in this distribution must be kept together, in original
  48. and unmodified form.
  49.  
  50.  
  51.  
  52.  
  53. Limitations.
  54.  
  55. THE PROGRAM IS PROVIDED TO YOU "AS IS," WITHOUT WARRANTY. THERE IS NO
  56. WARRANTY FOR THE PROGRAM, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT
  57. LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
  58. PARTICULAR PURPOSE AND NONINFRINGEMENT OF THIRD PARTY RIGHTS. THE ENTIRE
  59. RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD
  60. THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
  61. SERVICING, REPAIR OR CORRECTION.
  62.  
  63.  
  64.  
  65. IF YOU DO NOT ACCEPT THIS LICENCE, YOU MUST DELETE ALL FILES CONTAINED IN
  66. THIS ARCHIVE.
  67.  
  68. _____________________________________________________________________________
  69.  
  70.  
  71. Purpose of this program:
  72.  
  73.     Make the SetFunction (= patch function) of the OS safer, allow 
  74.     installation and removal of patches in any order.
  75.     Record the patches made and the program that made the patch.
  76.  
  77. This program is mainly intended as a debugging tool, for recording the patches
  78. installed and to capture illegal patches. It is, however, adviced to run with
  79. SaferPatches installed permanently.
  80.  
  81. SaferPatches will free the additional memory occupied by the patched functions
  82. automatically if a library is flushed later on.
  83.  
  84.  
  85.     SYNOPSIS:
  86.  
  87. SaferPatches    INSTALL    REMOVE REMEMBER WARN
  88.  
  89.  
  90. INSTALL        Add the "SaferPatches" patch to the system.
  91. REMOVE        Remove "SaferPatches" from the system. You are, however,
  92.         "recommanded" not to remove it once you've started it.
  93.         
  94. REMEMBER    This option can be given together with INSTALL. If present,
  95.         SaferPatches will store the names of the programs together
  96.         with the patch they added.
  97.  
  98. WARN        Saferpatches will guru with 0x10000026 if a removed vector
  99.         is still used.
  100.  
  101.  
  102.     SYNOPSIS:
  103.  
  104. ShowPatch    fd_dir
  105.  
  106.     Shows all patches added to the system, together with the entry point
  107.     and the program that added the patch, if available - see the
  108.     REMEMBER option of the Saferpatches program.
  109.  
  110.     If the "fd_dir" is given, ShowPatch will read standard ".fd"
  111.     library descriptions from that subdirectory and will present the
  112.     name of the entry point that has been patched as well.
  113.  
  114.  
  115. _____________________________________________________________________________
  116.  
  117. Compatibility:
  118.  
  119.     "SaferPatches" is NOT compatible to the following illegal patches:
  120. (see below for what is considered to be legal)
  121.  
  122.     -CEDPatch
  123.  
  124.  
  125.  
  126. The way "SaferPatches" operates conflicts with my debug utility "MemSniff".
  127. If you want to run both, "MemSniff" and "SaferPatches", you should add the
  128. command line option "SNIFF" to SaferPatches. You shouldn't provide that
  129. option in other situations.
  130.  
  131.  
  132. VirusZ might report that libraries got patched from time to time. This is
  133. because SaferPatches modifies the Expunge vector of all libraries in order
  134. to free the memory occupied by the patches if the library gets closed. This
  135. warning message is harmless.
  136.  
  137.  
  138. IMPORTANT:    !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
  139. Saferpatches MUST be run BEHIND SetPatch !!!!!!!!!!!!!!!!!
  140. IMPORTANT:    !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!    
  141.  
  142.  
  143. SaferPatches IS compatible to the debug tool PatchWork.
  144.  
  145. _____________________________________________________________________________
  146.  
  147. Gurus:
  148.  
  149.     Because "SaferPatches" is supposed to be a debug utility, it may
  150. create "guru meditations", i.e. software alerts. The following alerts may
  151. be created by SaferPatches:
  152.  
  153. 0x01000020        Patch vector out of range.
  154.         A program tried to patch a vector in a library that isn't
  155.         present.
  156.  
  157. 0x01000021        Entry is not patchable.
  158.         A program tried to install a patch into a vector that can't
  159.         be patched. Some vectors, like the GetCC() vector of
  160.         the exec lib are directly inlined functions that can't be
  161.         changed with SaferPatches. Same goes for the DOS library
  162.         of releases 32 to 35, but this has changed starting with
  163.         releases 36 and up of the OS.
  164.  
  165. 0x01000022        No mem for patch vector.
  166.         SaferPatches failed to allocate a vector for the patch.
  167.  
  168. 0x01000023        Patched vector to ROM.
  169.         A program attempted to patch one ROM vector to a second
  170.         vector which is actually in the ROM. Replacing one system
  171.         function by a different one is considered to be illegal.
  172.  
  173. 0x01000024        Found libentry without patches
  174.         SaferPatches found a library in its patch list that isn't
  175.         actually patched. This is an internal failure and shouldn't
  176.         occur.
  177.  
  178. 0x01000025        Unsafe patch
  179.         A program tried to patch one vector that can't be patched in
  180.         a safe way because it is called by the SetFunction procedure
  181.         itself. One example is "SetFunction", or "SumLibrary".
  182.  
  183. 0x01000026        Removed libentry patched
  184.         A libvector that has been removed was illegally called again.
  185.         A program restored an older patch, but was still calling the
  186.         obsolete return vector. This can only happen with WARN 
  187.         enabled.
  188.  
  189. 0x01000027        Function pointer is NULL
  190.         Somebody tried to patch a function to NULL.
  191.  
  192. _____________________________________________________________________________
  193.  
  194. Legal vs. illegal patching:
  195.  
  196. Three operations are considered to be "legal" patching operations:
  197.  
  198. 1)    Install a patch
  199. 2)    Remove a patch
  200. 3)    Verify, if a given patch is installed.
  201.  
  202. 3) is new to this implementation of SaferPatches and not having it messed the
  203. system with the RTPatch program.
  204.  
  205.  
  206. A legal way how to install a patch:
  207.  
  208.     -Call Forbid() or even Disable() in critical cases.
  209.     -Load the address of the new function in d0, the offset in a0,
  210.      the library and a1, and ExecBase in a6.
  211.     -Call SetFunction()
  212.     -Store the return value of SetFunction as pointer to the old function.
  213.     -Call Permit() or Disable().
  214.  
  215.  
  216. The following methods of installing patches ARE ILLEGAL:
  217.  
  218.     -Forgetting to Permit().
  219.     -Reading the vector directly from the library vectors instead of
  220.      using the return value.
  221.     -Using the return code of SetFunction for anything else except
  222.      jumping into the old code.
  223.     -Patching one OS function to a different one.
  224.     -Patching functions that can't be patched, like inline functions
  225.      or functions called by SaferPatches.
  226.     -Using anything else but the return code of SetFunction for calling
  227.      the old function.
  228.     -Writing the new function directly into the vector offset.
  229.  
  230.  
  231. A legal way to remove a patch:
  232.  
  233.     -Load d0 with the return code of SetFunction when installing the
  234.      patch. Load a1 with the base address of the library. Load a6
  235.      with execbase.
  236.     -Call SetFunction().
  237.  
  238. The following methods of removing a patch ARE ILLEGAL:
  239.  
  240.     -Use anything else but the return code of the installing SetFunction
  241.      for removing the patch again.
  242.     -Removing the new function by writing the old return code directly
  243.      into the vector offset.
  244.  
  245.  
  246. A legal way how to verify if your patch is still installed:
  247.  
  248.     -Call Forbid() or Disable()
  249.     -Call SetFunction with the same arguments AS IF you are installing
  250.      the patch again, this is:
  251.      Load the address of the new function in d0,the library base in a1
  252.      and ExecBase in a6 and offset in a0. Call SetFunction.
  253.     -Check the return code. If it is the same pointer you passed in d0
  254.      to SetFunction, your patch is still active. It has been installed
  255.      now and must/can be removed if it is anything else. 
  256.     -Call Permit() or Enable().
  257.  
  258. This method is used by the RTPatch program and also considered to be legal.
  259.  
  260. The following verify methods are considered to be illegal:
  261.  
  262.     -Failing to call Forbid().
  263.     -Reading the vector entry for the vector base directly.
  264.  
  265. _____________________________________________________________________________
  266.  
  267. New in 2.07:
  268.  
  269. Added another GURU, added the WARN option to turn off the 0x01000026 guru.
  270. Patched the close function for completeness (forgot again about the delayed
  271. expunge function, sigh.). Updates the SHOWPATCH program. Added a SetMan port
  272. of completeness.
  273. _____________________________________________________________________________
  274.  
  275. New in 2.06:
  276.  
  277. Added a new GURU and fixed a bug of the Expunge replacement. Thanks to
  278. Magnus for reporting!
  279. _____________________________________________________________________________
  280.  
  281. Thomas,
  282.     November 1997
  283.